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Defining a Mock Class 

Mocking a Normal Class 

Given 

class Foo { 
virtual ~Foo(); 

virtual int GetSizeO const = 0; 
virtual string DescribeCconst char* name) = 0: 
virtual string DescribeCint type) = 0; 
virtual bool ProcessfBar elem, int count) = 0; 
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(note that ~FooO must be virtual) we can define its mock as 

# include "gmock/gmock.h" 

class MockFoo : public Foo { 

MOCK_CONST_METHOD0(GetSize, intO); 

MOCK_METHODl(Describe, string(const char* name)); 

MOCK_METHODl(Describe, string(int type)); 

M0CK_METH0D2(Process , boolCBar elem, int count)); 

}; 

To create a "nice" mock object which ignores all uninteresting calls, or a "strict" mock object, which treats them as failures: 

NiceMock<MockFoo> nice_foo; // The type is a subclass of MockFoo. 

StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo. 

Mocking a Class Template 

To mock 

template <typename Elem> 
class Stacklnterface { 
public: 

virtual -StacklnterfaceO; 
virtual int GetSizeO const = 0; 
virtual void Push(const Elem& x) = 0; 

}; 


(note that ~StackInterface() must be virtual) just append _T to the M0CK_* macros: 

template <typename Elem> 

class MockStack : public StackInterface<Elem> { 
public: 

MOCK_CONST_METHOD0_T(GetSize , intO); 

M0CK_METH0D1_T (Push, voidCconst Elem& x)); 

} ; 

Specifying Calling Conventions for Mock Functions 

If your mock function doesn't use the default calling convention, you can specify it by appending _WITH_CALLTYPE to any of the macros 
described in the previous two sections and supplying the calling convention as the first argument to the macro. For example, 

M0CK_METH0D_1_WITH_CALLTYPE(STDMETH0DCALLTYPE, Foo, bool(int n)); 

M0CK_C0NST_METH0D2_WITH_CALLTYPE(STDMETH0DCALLTYPE , Bar, int(double x, double y)); 

where STDMETHODCALLTYPE is defined by <objbase.h> on Windows. 

Using Mocks in Tests 

The typical flow is: 

1. Import the Google Mock names you need to use. All Google Mock names are in the testing namespace unless they are macros or 
otherwise noted. 

2. Create the mock objects. 

3. Optionally, set the default actions of the mock objects. 

4. Set your expectations on the mock objects (How will they be called? What wil they do?). 

5. Exercise code that uses the mock objects; if necessary, check the result using Google Test assertions. 

6. When a mock objects is destructed, Google Mock automatically verifies that all expectations on it have been satisfied. 

Here is an example: 

using : :testing: :Return; // #1 

TESTCBarTest, DoesThis) { 
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0N_CALL(foo, GetSizeO) // #3 

.WillByDefault(Return(l)); 

// ... other default actions ... 

EXPECT_CALL(foo, Described)) // #4 

.Times(3) 

.WillRepeatedly(Return("Category 5")); 

// . . . other expectations . . . 

EXPECT_EQ("good", MyProductionFunction(&foo)); // #5 

} // #6 

Setting Default Actions 

Google Mock has a built-in default action for any function that returns void, bool, a numeric value, or a pointer. 

To customize the default action for functions with return type T globally: 
using : rtesting: :DefaultValue ; 

DefaultValue<T>: :Set(value); //Sets the default value to be returned. 

// ... use the mocks . . . 

DefaultValue<T>: :ClearO; //Resets the default value. 

To customize the default action for a particular method, use 0N_CALLO: 

ON_CALL(mock_object, method(matchers)) 

.With(multi_argument_matcher) ? 

.WillByDefault(action); 

Setting Expectations 

EXPECT_CALLO sets expectations on a mock method (How will it be called? What will it do?): 

EXPECT_CALL(mock_object , method(matchers)) 

.WithCmulti_argument_matcher) ? 

.TimesCcardinality) ? 

.InSequence(sequences) * 

.After(expectations) * 

.WillOnce(action) * 

.WillRepeatedlyCaction) ? 

.RetiresOnSaturationO; ? 

If TimesO is omitted, the cardinality is assumed to be: 

• Times(l) when there is neither WillOnceO norWillRepeatedlyO; 

• Times(n) when there are n WillOnceOs but no WillRepeatedlyO, where n >= 1; or 

• TimesCAtLeastCn)) when there are n WillOnceOs and a WillRepeatedlyO, where n >= 0. 

A method with no EXPECT_CALLO is free to be invoked any number of times, and the default action will be taken each time. 

Matchers 

A matcher matches a single argument. You can use it inside ONLCALLO or EXPECT_CALLO, or use it to validate a value directly: 


EXPECT_THAT (value , matcher) 

Asserts that value matches matcher. 

AS S E RT_THAT (value, matcher) 

The same as EXPECT_THAT(value, matcher), except that it generates a fatal failure. 


Built-in matchers (where argument is the function argument) are divided into several categories: 

Wildcard 


- 

argument can be any value of the correct type. 

A<type>C) or An<type>C) 

argument can be any value of type type. 
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Eq(value) or value 

argument == value 

Ge (value) 

argument >= value 

Gt (value) 

argument > value 

Le(value) 

argument <= value 

Lt (value) 

argument < value 

Ne (value) 

argument != value 

IsNullO 

argument is a NULL pointer (raw or smart). 

NotNulTQ 

argument is a non-null pointer (raw or smart). 

Ref(variable) 

argument is a reference to variable. 

TypedEq<type> 

(value) 

argument has type type and is equal to value. You may need to use this instead of Eq(value) when the mock 
function is overloaded. 


Except RefO, these matchers make a copy of value in case it's modified or destructed later. If the compiler complains that value doesn't have 
a public copy constructor, try wrap it in ByRefO, e.g. Eq(ByRef(non_copyable_value)). If you do that, make sure non_copyable_value is not 
changed afterwards, or the meaning of your matcher will be changed. 


Floating-Point Matchers 


DoubleEq(a_double) 

argument is a double value approximately equal to a_double, treating two NaNs as unequal. 

FloatEq(a_float) 

argument is a float value approximately equal to a_float, treating two NaNs as unequal. 

NanSensitiveDoubleEq(a_double) 

argument is a double value approximately equal to a_double, treating two NaNs as equal. 

NanSensitiveFloatEq(a_float) 

argument is a float value approximately equal to a_float, treating two NaNs as equal. 


The above matchers use ULP-based comparison (the same as used in Google Test ! They automatically pick a reasonable error bound based on 
the absolute value of the expected value. DoubleEqO and FloatEqO conform to the IEEE standard, which requires comparing two NaNs for 
equality to return false. The NanSensitive* version instead treats two NaNs as equal, which is often what a user wants. 


Doubl eNea r (a_doubl e , max_abs_e r ro r) 

argument is a double value close to a_double (absolute error <= max_abs_error), treating 
two NaNs as unequal. 

FloatNear(a_float, max_abs_error) 

argument is a float value close to a_float (absolute error <= max_abs_error), treating two 
NaNs as unequal. 

NanSensitiveDoubleNear(a_double, 

max_abs_error) 

argument is a double value close to a_double (absolute error <= max_abs_error), treating 
two NaNs as equal. 

NanSensitiveFloatNear(a_float, 

max_abs_error) 

argument is a float value close to a_float (absolute error <= max_abs_error), treating two 
NaNs as equal. 


String Matchers 


The argument can be either a C string or a C++ string object: 


Contai nsRegex(st ri ng) 

argument matches the given regular expression. 

EndsWith(suffix) 

argument ends with string suffix. 

HasSubstr(string) 

argument contains string as a sub-string. 

MatchesRegex(string) 

argument matches the given regular expression with the match starting at the first character and ending at the last 
character. 

StartsWith(prefix) 

argument starts with string prefix. 

StrCaseEq(string) 

argument is equal to string, ignoring case. 

StrCaseNe(string) 

argument is not equal to string, ignoring case. 

StrEq(string) 

argument is equal to string. 

StrNe(string) 

argument is not equal to string. 
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ContainsRegexO and MatchesRegexO use the regular expression syntax defined here . StrCaseEqO, StrCaseNeO, StrEqO, and StrNeO 
work for wide strings as well. 

Container Matchers 

Most STL-style containers support ==, so you can use Eq(expected_container) or simply expected_container to match a container exactly. 
If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use: 


Contai nerEq(contai ner) 

The same as Eq(container) except that the failure message also includes which elements are 
in one container but not the other. 

Contains(e) 

argument contains an element that matches e, which can be either a value or a matcher. 

Each(e) 

argument is a container where every element matches e, which can be either a value or a 
matcher. 

ElementsAre(e0, el, ..., en) 

argument has n + 1 elements, where the i-th element matches ei, which can be a value or a 
matcher. 0 to 10 arguments are allowed. 

ElementsAreArray({ e0, el, . . . , en 
}), ElementsAreArray(array), or 
ElementsAreArray(array, count) 

The same as ElementsAreO except that the expected element values/matchers come from an 
initializer list, vector, or C-style array. 

IsEmptyO 

argument is an empty container (container. emptyO). 

Pointwise(m, container) 

argument contains the same number of elements as in container, and for all i, (the i-th element 
in argument, the i-th element in container) match m, which is a matcher on 2-tuples. E.g. 
Pointwise(Le(), upper_bounds) verifies that each element in argument doesn't exceed the 
corresponding element in upper_bounds. 

Sizels(m) 

argument is a container whose size matches m. E.g. Sizels(2) or SizeIs(Lt(2)). 

UnorderedEiementsAre(e0, el, . . . , 
en) 

argument has n + 1 elements, and under some permutation each element matches an ei (for a 
different i), which can be a value or a matcher. 0 to 10 arguments are allowed. 

UnorderedElementsAreArray({ e0, el, 
en }), 

UnorderedElementsAreArray(array), or 

UnorderedElementsAreArray(array, 

count) 

The same as UnorderedElementsAreO except that the expected element values/matchers 
come from an initializer list, vector, or C-style array. 

WhenSorted(m) 

When argument is sorted using the < operator, it matches container matcher m. E.g. 
WhenSorted(UnorderedElementsAre(l, 2, 3)) verifies that argument contains elements 1, 2, 
and 3, ignoring order. 

WhenSortedBy(comparator, m) 

The same as WhenSorted(m), except that the given comparator instead of < is used to sort 
argument. E.g. WhenSortedBy(std: :greater<int>(), ElementsAre(3, 2, 1)). 


These matchers can also match: 

1. a native array passed by reference (e.g. in Foo(const int (&a)[5])), and 

2. an array passed as a pointer and a count (e.g. in Bar(const T* buffer, int len) - see Multi-argument Matchers !, 
where the array may be multi-dimensional (i.e. its elements can be arrays). 

Member Matchers 


Field(&class: :field, m) 

argument. field (or argument ->fi eld when argument is a plain pointer) matches matcher m, where 
argument is an object of type class. 

KeyCe) 

argument, first matches e, which can be either a value ora matcher. E.g. Contains(Key(Le(5))) can 
verify that a map contains a key <= 5. 

Pair(ml, m2) 

argument is an std: :pair whose first field matches ml and second field matches m2. 

Property(&class: : property, 
m) 

argument. propertyO (or argument->property() when argument is a plain pointer) matches matcher m, 
where argument is an object of type class. 


Matching the Result of a Function or Functor 


ResultOf(f , m) f (argument) matches matcher m, where f is a function or functor. 


Pointer Matchers 
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| Point eeQrQ ; argument (either a smart pointer or a raw pointer) points to a value that matches matcher m. 

Multiargument Matchers 

Technically, all matchers match a single value. A "multi-argument 1 ' matcher is just one that matches a tuple. The following matchers can be 
used to match a tuple (x, y): 


EqO 

x == y 

GeO 

x >= y 

GtO 

x > y 

LeO 

x <= y 

LtO 

x < y 

NeQ 

x != y 


You can use the following selectors to pick a subset of the arguments (or reorder them) to participate in the matching: 


AllArgsCm) 

Equivalent to m. Useful as syntactic sugar in .WithCAllArgsCm)). 

Args<Nl, N2, NMjrf) 

The tuple of the k selected (using 0-based indices) arguments matches m, e.g. Args<l, 2>(EqQ). 


Composite Matchers 


You can make a matcher from one or more other matchers: 


AUOfOnl, m2, mn) 

argument matches all of the matchers ml to mn. 

AnyOf (ml , m2 , . . . , mn) 

argument matches at least one of the matchers ml to mn. 

Not Cm) 

argument doesn't match matcher m. 


Adapters for Matchers 


MatcherCast<T>Cm) 

casts matcher m to type Matcher<T>. 

SafeMatcherCast<T>Cm) 

safelv casts matcher m to tvDe Matcher<T>. 

TrulyCpredicate) 

predicateCargument) returns something considered by C++ to be true, where predicate is a function or functor. 


Matchers as Predicates 


MatchesCm) Cval ue) 

evaluates to true if value matches m. You can use MatchesCm) alone as a unary 
functor. 

ExplainMatchResultCm, value, 
resultJListener) 

evaluates to true if value matches m, explaining the result to resultJListener. 

ValueCvalue, m) 

evaluates to true if value matches m. 


Defining Matchers 


MATCHERCIsEven, "") { return Carg % 2) = 0; } 

Defines a matcher IsEvenC) to 
match an even number. 

MATCHER_PCIsDivisibleBy, n, "") { *result_listener « "where the remainder is " « 
Carg % n); return Carg % n) == 0; } 

Defines a macher IsDivisibleByCn) 
to match a number divisible by n. 

MATCHER_P2CIsBetween, a, b, std: :stringCnegation ? "isn't" : "is") + " between " + 
PrintToStringCa) + " and " + PrintToStringCb)) { return a <= arg && arg <= b; } 

Defines a matcher IsBetweenCa, b) 
to match a value in the range [a, b]. 


Notes: 

1. The MATCHER* macros cannot be used inside a function or class. 

2. The matcher body must be purely functional (i.e. it cannot have any side effect, and the result must not depend on anything other than the 
value being matched and the matcher parameters). 

3. You can use PrintToString(x) to convert a value x of any type to a string. 
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Matchers as Test Assertions 


ASSERT_THAT(expression, m) 

Generates a fatal failure if the value of exDression doesn't match matcher m. 

EXPECT_THAT (expression , m) 

Generates a non-fatal failure if the value of expression doesn't match matcher m. 


Actions 


Actions specify what a mock function should do when invoked. 

Returning a Value 


ReturnO 

Return from a void mock function. 

Return(value) 

Return value. If the type of value is different to the mock function's return type, value is converted to the latter 
type at the time the expectation is set , not when the action is executed. 

ReturnArg<N>0 

Return the N-th (0-based) argument. 

ReturnNew<T>(al, . . . , 
ak) 

Return new T(al, . . . , ak); a different object is created each time. 

ReturnNullO 

Return a null pointer. 

ReturnPointee(ptr) 

Return the value pointed to by ptr. 

ReturnRef (variable) 

Return a reference to variable. 

ReturnRefOfCopy(value) 

Return a reference to a copy of value; the copy lives as long as the action. 


Side Effects 


AssignC&variable, value) 

Assign value to variable. 

DeleteArg<N>C) 

Delete the N-th (0-based) argument, which must be a pointer. 

SaveArg<N>(pointer) 

Save the N-th (0-based) argument to *pointer. 

SaveArgPoi ntee<N> 
(pointer) 

Save the value pointed to by the N-th (0-based) argument to *pointer. 

SetArgReferee<N>(value) 

Assign value to the variable referenced by the N-th (0-based) argument. 

SetArgPointee<N>(value) 

Assign value to the variable pointed by the N-th (0-based) argument. 

SetArgumentPoi ntee<N> 
(value) 

Same as SetArgPointee<N>(value). Deprecated. Will be removed in vl.7.0. 

SetArrayArgument<N> 
(first, last) 

Copies the elements in source range [first, last) to the array pointed to by the N-th (0-based) argument, 
which can be either a pointer or an iterator. The action does not take ownership of the elements in the source 
range. 

SetErrnoAndReturn(error, 

value) 

Set errno to error and return value. 

Throw( exception) 

Throws the given exception, which can be any copyable value. Available since vl.1.0. 


Using a Function or a Functor as an Action 


Invoke (f) 

Invoke f with the arguments passed to the mock function, where f can be a global/static 
function or a functor. 

Invoke(object_pointer, &class: : method) 

Invoke the {method on the object with the arguments passed to the mock function. 

InvokeWithoutArgs(f) 

Invoke f, which can be a global/static function or a functor, f must take no arguments. 

InvokeWithoutArgs(object_pointer, 

&class: : method) 

Invoke the method on the object, which takes no arguments. 

InvokeArgument<N>(argl, arg2, ..., 

Invoke the mock function's N-th (0-based) argument, which must be a function or a functor, 
with the k arguments. 


The return value of the invoked function is used as the return value of the action. 
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When defining a function or functor to be used with lnvoke*0, you can declare any unused parameters as Unused: 

double DistanceCUnused, double x, double y) { return sqrt(x*x + y*y); } 

EXPECT_CALLOnock, Foo("Hi% _)).WillOnce(;invoke(Distance)); 

In InvokeArgument<N>( . . .), if an argument needs to be passed by reference, wrap it inside ByRef(). For example, 
InvokeArgument<2>(5, stringC'Hi"), ByRef(foo)) 
calls the mock function's #2 argument, passing to it 5 and stringC'Hi") by value, and foo by reference. 

Default Action 

DoDefaultQ Do the default action (specified by ONLCALLQ or the built-in one). 


Note: due to technical reasons, DoDefaultO cannot be used inside a composite action - trying to do so will result in a run-time error. 

Composite Actions 


DoAllCal, a2, an) 

Do all actions al to an and return the result of an in each invocation. The first n - 1 sub-actions must return 
void. 

IgnoreResult(a) 

Perform action a and ignore its result, a must not return void. 

WithArg<N>(a) 

Pass the N-th (0-based) argument of the mock function to action a and perform it. 

WithArgs<Nl, N2, ..., Nk> 

Ca) 

Pass the selected (0-based) arguments of the mock function to action a and perform it. 

WithoutArgsCa) 

Perform action a without any arguments. 


Defining Actions 


ACTION(Sum) { return arg0 + argl; } 

Defines an action Sum() to return the sum of the mock function's argument #0 and #1 . 

ACTI0N_P(Plus, n) { return arg0 + n; } 

Defines an action Plus(n) to return the sum of the mock function's argument #0 and n. 

ACTI0N_Pk(Foo, pi, ..., pk) { statements; } 

Defines a parameterized action FooCpl, . . . , pk) to execute the given statements. 


The ACTION* macros cannot be used inside a function or 


Cardinalities 


These are used in TimesO to specify how many times a mock function will be called: 


AnyNumberO 

The function can be called any number of times. 

AtLeast(n) 

The call is expected at least n times. 

AtMost(n) 

The call is expected at most n times. 

Between(m, n) 

The call is expected between m and n (inclusive) times. 

Exactly(n) or n 

The call is expected exactly n times. In particular, the call should never happen when n is 0. 


Expectation Order 

By default, the expectations can be matched in any order. If some or all expectations must be matched in a given order, there are two ways to 
specify it. They can be used either independently or together. 

The After Clause 


using :: testing: Expectation; 

Expectation init_x = EXPECT_CALL(foo, InitXO); 

Expectation init_y = EXPECT_CALL(foo, InitYO); 
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.After(init_x, init_y); 
says that BarO can be called only after both InitXO and InitYO have been called. 

If you don't know how many pre-requisites an expectation has when you write it, you can use an ExpectationSet to collect them: 

using : rtesting: : ExpectationSet; 

ExpectationSet aVL_inits; 
for (int i = 0; i < element_count; i++) { 
aVL_inits += EXPECT_CALL(foo, InitElement(i)); 

} 

EXPECT_CALL(foo, BarO) 

.AfterCall_inits); 

says that BarO can be called only after all elements have been initialized (but we don't care about which elements get initialized before the 
others). 

Modifying an ExpectationSet after using it in an .AfterO doesn't affect the meaning of the .AfterC). 

Sequences 

When you have a long chain of sequential expectations, it's easier to specify the order using sequences, which don't require you to given each 
expectation in the chain a different name. All expected calls in the same sequence must occur in the order they are specified. 

using : :testing: :Sequence ; 

Sequence si, s2; 

EXPECT_CALL(foo, ResetO) 

.InSequenceCsl, s2) 

.WillOnce(ReturnCtrue)); 

EXPECT_CALL(foo, GetSizeO) 

.InSequenceCsl) 

.WillOnce(ReturnCl)); 

EXPECT_CALLCfoo, DescribeCA<const char*>())) 

.InSequenceCs2) 

.WillOnce(ReturnC"dummy")); 

says that ResetO must be called before both GetSizeO and DescribeO, and the latter two can occur in any order. 

To put many expectations in a sequence conveniently: 

using : :testing: :InSequence; 

{ 

InSequence dummy; 

EXPECT_CALLC. ..)...; 

EXPECT_CALLC. ..)...; 

EXPECT_CALLC. ..)...; 

} 

says that all expected calls in the scope of dummy must occur in strict order. The name dummy is irrelevant.) 

Verifying and Resetting a Mock 

Google Mock will verify the expectations on a mock object when it is destructed, or you can do it earlier: 
using : :testing: :Mock; 

// Verifies and removes the expectations on mock_obj; 

// returns true iff successful. 

Mock: : VerifyAndCl ear ExpectationsC&mock_obj); 

// Verifies and removes the expectations on mock_obj; 

// also removes the default actions set by 0N_CALLO; 

// returns true iff successful. 

Mock: : VerifyAndCl ear C&mock_obj); 

You can also tell Google Mock that a mock object can be leaked and doesn't need to be verified: 
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Mock: :AllowLeak(&mock_obj); 

Mock Classes 


Google Mock defines a convenient mock class template 

class MockFunction<RCAl, An> { 

public: 

MOCK_METHODnCCall, R(A1, An)); 

}; 


See this recipe for one application of it. 

Flags 


- - gmoc k_catch_l eaked_mocks=0 

Don't report leaked mock objects as failures. 

— gmoc k_ve rbose=L E VE L 

Sets the default verbosity level (info, warning, or error) of Google Mock messages. 
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